docs: Add note about stable sorting to SortListModel

diff --git a/gtk/gtksortlistmodel.c b/gtk/gtksortlistmodel.c
index 3a1d14fe05366cc1e08eea4ad880a77f19602dc3..2d706ba5219de2db11d77912b392b13128da1f3b 100644 (file)
--- a/gtk/gtksortlistmodel.c
+++ b/gtk/gtksortlistmodel.c
@@ -58,6 +58,13 @@
  * A `GListModel` that sorts the elements of an underlying model
  * according to a `GtkSorter`.
  *
+ * The model is a stable sort. If two items compare equal according
+ * to the sorter, the one that appears first in the original model will
+ * also appear first after sorting.
+ * Note that if you change the sorter, the previous order will have no
+ * influence on the new order. If you want that, consider using a
+ * `GtkMultiSorter` and appending the previous sorter to it.
+ *
  * The model can be set up to do incremental sorting, so that
  * sorting long lists doesn't block the UI. See
  * [method@Gtk.SortListModel.set_incremental] for details.